stanfordfandomcom-20200214-history
FDTD Plus
This is a Wiki for a finite-difference time-domain (FDTD) simulation software package developed by the research group of Shanhui Fan at Stanford University. The purpose of this Wiki is to * document the software package. * allow group members to post feedback on the software. = Overview = The name of the FDTD software package is FDTD Plus. Currently, a parallel version of FDTD Plus is available to Fan group members at Shanhuiserve, Bigben, NCSA and SDSC. =User input file= In order to run FDTD Plus, a user input file must be written. This user input file contains details on the structure to be simulated, and the outputs required from the simulation. This section describes the different possible user inputs available. Inputs are grouped into five groups, namely Options, Materials, Sources, Objects and Outputs. = Options = This user input sets up the dimensions, boundaries and cell type for the simulation. syntax: (Option OptionType ) *In the definition of the different options below, any option that is not marked "(optional)" is a required option. CellParam Defines the type of cell used in the FDTD computation including the field type. (Option CellParam (CellType value) (FieldType value) (PrecisionType value) ) CellType The type of cells used to represent the materials in the computation region, value\in\{linear \} , *linear is a field independent material. FieldType The mathematical field type of the physical fields within the cell, value\in\{complex, real \} . *This option only sets the mathematic field type of physical fields that are communicated between cells. PrecisionType (optional) The floating point precision of fields, coefficients etc in the cell, value\in\{double, float \} . *Default value = double. DimensionParam Defines the spatial and time dimensions of the compute region. (Option DimensionParam (LengthScale (Value value) ) (Center (X value) (Y value) (Z value) ) (Size (X value) (Y value) (Z value) ) (Resolution (X value) (Y value) (Z value) ) (TimeParam (Start value) (End value) ) ) LengthScale (optional) The length scale of the compute region, value\in\mathbb{R}_{>0} . *LengthScale is only required to be defined for frequency dependent or lossy materials. Center The center of the compute region, value\in\mathbb{R} *Unit = LengthScale. Size The size of the compute region, value\in\mathbb{R}_{>0} *Unit = LengthScale. Resolution The spatial increment in the compute region, value\in\mathbb{R}_{>0} *Unit = LengthScale. TimeParam The time parameters for the FDTD run. Start (optional) The start time of computation value\in\mathbb{R} *Unit = LengthScale / c, where c = speed of light in vacuum. *Default value = 0. End The end time of computation value\in\mathbb{R}_{\geq{Start}} *Unit = LengthScale / c. BoundaryParam Defines the boundaries of the compute region. (Option BoundaryParam (Type (X value) (Y value) (Z value) ) (PmlParam (Size (X value1 value2) (Y value1 value2) (Z value1 value2) ) (Type value) (DecayConstant value) ) (BlochK (X value) (Y value) (Z value) ) (Symmetry (X value) (Y value) (Z value) ) ) Type The type of boundaries in the compute region, value\in\{pml, bloch, none \} , *pml is a Perfectly Matched Layer ([http://en.wikipedia.org/wiki/Perfectly_Matched_Layer PML]) boundary, *bloch is a [http://en.wikipedia.org/wiki/Bloch_wave Bloch] boundary, *none results in the boundary that includes the origin of the compute region to be of type PEC (E-fields parallel to boundary set to zero), and the opposite boundary of the compute region to be of type PMC (H-fields parallel to boundary set to zero). PmlParam (optional) The parameters for PML boundaries. *PmlParam is only required to be defined if any BoundaryParam::Type pml. Size The size of PML boundaries. *Size is included in DimensionParam::Size. *Size is only required to be defined for directions with BoundaryParam::Type pml. =value1 = The PML boundary size for boundaries that include the origin of the compute region, value1\in\mathbb{R}_{\geq{0}} *Unit = DimensionParam::LengthScale. =value2 (optional = The PML boundary size for boundaries that do not include the origin of the compute region, value2\in\mathbb{R}_{\geq{0}} *Unit = DimensionParam::LengthScale. *Default value = value2 . Type The type of PML boundary, value\in\{upml \} , *upml is a Uniaxial PML. DecayConstant (optional) The PML decay constant, value\in\mathbb{R}_{>0} *Unit = c / DimensionParam::LengthScale. *Default value = 1\times{10}^{-6} . BlochK (optional) The Bloch k-vector for Bloch boundaries, value\in\mathbb{R} *Unit = 2\pi / DimensionParam::Size. *BlochK is only required to be defined for directions with BoundaryParam::Type bloch. *When BoundaryParam::Type bloch, only Bloch k-vector value = 0 allows CellParam::FieldType = real. Symmetry (optional) For a compute region that has mirror symmetry in any direction, this option enforces the symmetry at the center plane normal to that direction (i.e. each symmetry results in a reduction by half of the corresponding DimensionParam::Size used for FDTD computation), value\in\{pec, pmc \} , *pec results in a Perfect Electric Conductor (PEC) center plane where the E-fields parallel to the plane are set to zero. *pmc results in a Perfect Magnetic Conductor (PMC) center plane where the H-fields parallel to the plane are set to zero. OutputStructure (optional) Prints the structure within the compute region into a hdf5 file. (Option OutputStructure (FileName value) ) *This option is disabled by default. FileName (optional) The name of the output file, value\in{s}tring . *Default value = "structure". *The suffix ".h5" is added to FileName. CheckInput (optional) Option to check the user input file. This option runs the simulation up to the point before cell construction. (Option CheckInput) *This option is disabled by default. *This option does run OutputStructure if it is enabled. = Materials = This user input defines a material type. syntax: (Material MaterialType (MaterialName value) (MaterialToken value) ) Common material parameters MaterialName The name of the material, value\in{s}tring . *Duplicate MaterialName values are not allowed. *"vacuum" is a reserved MaterialName. MaterialToken The index of the material (used by OutputStructure to print material), value\in\mathbb{I}_{>0} . *Duplicate MaterialToken values are not allowed. *0 is a reserved MaterialToken for "vacuum". =Linear materials= These are the material types defined for CellParam::CellType = linear. Lossless Defines a lossless MaterialType. (Material Lossless (MaterialName value) (MaterialToken value) (RelPermittivity value) (RelPermeability value) ) RelPermittivity The relative permittivity of the material, value\in\mathbb{R} . RelPermeability The relative permeability of the material, value\in\mathbb{R} . Lossy Defines a lossy MaterialType. (Material Lossy (MaterialName value) (MaterialToken value) (RelPermittivity value) (RelPermeability value) (Conductivity value) ) *The parameters for Lossy are the same as Lossless except for the additional conductivity parameter. *Option::DimensionParam::LengthScale must be defined for Lossy. Conductivity The conductivity of the material, value\in\mathbb{R} . *Unit = siemens/meter. PRP Defines an arbitrary dispersive MaterialType based on general complex-conjugate pole-residue pairs (PRP). (Material Lossless (MaterialName value) (MaterialToken value) (RelPermeability value) (EpsilonInfinity value) (PoleResiduePair (Pair1 pole_value residue_value ) (Pair2 pole_value residue_value ) | | | (PairN pole_value residue_value ) ) ) *Option::DimensionParam::LengthScale must be defined for PRP. *PRP can be used with Option::CellParam::FieldType = real. EpsilonInfinity The relative permittivity at infinite frequency, value\in\mathbb{R} . PoleResiduePair The N pole-residue pairs, pole\_value,\:residue\_value\:\in\:\mathbb{C} . *Unit = radians/second. *If your Xth (pole, residue) pair is (a + j b, c + j d), the format for entry into the PoleResiduePair parameter is (PairX (a, b) (c, d) ). =Outputs= This user input defines the outputs of the FDTD simulation. syntax: (Output OutputType (StartTime value) (EndTime value) (TimeStep value) (FileName value) ) *The leap frog algorithmn of FDTD results in field components being stored at different time points and different spatial points. *Before any output computation below, each field component is spatially averaged (with the corresponding field components in its neighboring cells) to the same spatial point wihin the cell; in addition, time averaging is performed to obtain all field components at the same time point. Common output parameters StartTime The start time of the output, value\in\mathbb{R} *Unit = Option::DimensionParam::LengthScale / c. EndTime The end time of the output, value\in\mathbb{R}_{>StartTime} *Unit = Option::DimensionParam::LengthScale / c. TimeStep The time step of the output, value\in\mathbb{R} *Unit = Option::DimensionParam::LengthScale / c. FileName The name of the file, value\in{s}tring . FieldTime Output selected fields at a particular point, (Output FieldTime (Position x_value y_value z_value) (OutputField value) (StartTime value) (EndTime value) (TimeStep value) (FileName value) ) Position The position coordinate at which output is performed, x\_value,y\_value,z\_value\in\mathbb{R} . OutputField These are the fields requested. Possible values are dependent on value of CellParam::CellType. *See below for material dependent definitions. FieldSpace Output selected fields in the whole compute region, (Output FieldSpace (OutputField value) (StartTime value) (EndTime value) (TimeStep value) (FileName value) ) *The output is performed into a hdf5 file; the suffix ".h5" is added to FileName). *To do (in future release) **Only the real part of the field is output currently; need to allow for other outputs. **To allow the output of the field in a plane instead of the whole region. FluxTimePlane At each requested TimeStep, output the sum of the time average Poynting vector over the plane, (Output FluxTimePlane (Center x_value y_value z_value) (NormalDirection value) (Size value0 value1) (StartTime value) (EndTime value) (TimeStep value) (FileName value) ) *Unit = Watts\cdot\left(Option::DimensionParam::LengthScale\right)^{2} *The sum of the time average Poynting vector over the plane is defined as, \frac{1}{2}\Delta_{1}\Delta_{2}\sum_{plane}\hat{n}\cdot{R}eE(r,t)^{*}\times{H(r,t)} * \Delta_{1},\Delta_{2} are the Option::DimensionParam::Resolution along the two perpendicular axes parallel to the plane (see Size below). * \hat{n} is the unit normal axis of the plane. Center The center coordinate of the plane, x\_value,y\_value,z\_value\in\mathbb{R} . *Unit = Option::DimensionParam::LengthScale. NormalDirection The normal direction of the plane, value\in\{\:positive_x, positive_y,positive_z,negative_x,negative_y,negative_z \:\} . Size The size along the two perpendicular axis parallel to the plane, value0,value1\in\mathbb{R} . *Unit = Option::DimensionParam::LengthScale. *For NormalDirection = positive_x, negative_x, value0 corresponds to size along y-axis and value1 corresponds to size along z-axis. *For NormalDirection = positive_y, negative_y, value0 corresponds to size along x-axis and value1 corresponds to size along z-axis. *For NormalDirection = positive_z, negative_z, value0 corresponds to size along x-axis and value1 corresponds to size along y-axis. *To do **Implement time average Poynting vector through a box. FluxSpectraPlane Output the transmitted power spectra through a plane, (Output FluxSpectraPlane (Center x_value y_value z_value) (NormalDirection value) (Size value0 value1) (StartTime value) (EndTime value) (TimeStep value) (StartFrequency value) (EndFrequency value) (FrequencyStep value) (AdjustParam value) (FileName value) ) *Unit = Watts\cdot\left(Option::DimensionParam::LengthScale\right)^{2} *Calculating the transmitted power spectra involves, **taking the Discrete Fourier Transform (DFT) of each field parallel to the plane from StartTime to EndTime. The DFT performed for field F(r, t) at spatial point r and frequency \omega is F(r, \omega)=\sum_{t'=StartTime}^{EndTime}F(r,t')\cdot\cos\left\omegat'\right *The sum of the time average Poynting vector over the plane is defined as, \frac{1}{2}\Delta_{1}\Delta_{2}\sum_{plane}\hat{n}\cdot{R}eE(r,t)^{*}\times{H(r,t)} * \Delta_{1},\Delta_{2} are the Option::DimensionParam::Resolution along the two perpendicular axes parallel to the plane (see Size below). * \hat{n} is the unit normal axis of the plane. *The plane parameters Center, NormalDirection and Size are the same as FluxTimePlane. StartFrequency The start frequency of the flux spectra calculation, value\in\mathbb{R}_{>0} *Unit = 2\pi c / Option::DimensionParam::LengthScale. EndFrequency The end frequency of the flux spectra calculation, value\in\mathbb{R}_{>0} *Unit = 2\pi c / Option::DimensionParam::LengthScale. FrequencyStep The frequency step of the flux spectra calculation, value\in\mathbb{R}_{>0} *Unit = 2\pi c / Option::DimensionParam::LengthScale. *and computing the the complex Poynting vector over the plane at EndTime. The complex Poynting vector is given as S=\frac{1}{2}ReE\times{H}^{*} through a plane, Linear material outputs This section defines the material dependent parameters and computation related to outputs for CellParam::CellType = linear. OutputField The fields requested, value\in\{all, ex,ey,ez,hx,hy,hz \} . (Note: OutputField can be any combination of above values; for example, (OutputField ex ey hz) will only output Ex-, Ey- and Hz-fields). =Objects= This user input defines the objects that can be built in the compute region. syntax: (Output ObjectType (Center x_value y_value z_value) (MaterialName/SourceName value) (Array (Axis0 x_value y_value z_value) (Axis1 x_value y_value z_value) (Axis2 x_value y_value z_value) (Period value0 value1 value2) (NoPeriod value0 value1 value2) ) ) *Either a Source or Material can be attached to an object. Common object parameters Center The center coordinate of the object, x\_value,y\_value,z\_value\in\mathbb{R} . *Unit = Option::DimensionParam::LengthScale. MaterialName/SourceName The MaterialName (SourceName) of a defined Material (Source), value\in{s}tring . *Defining both MaterialName and SourceName for the same object will throw an initialization error. If you want to define a source and a material at the same point, you have to use separate objects. Array (optional) Creates an array of the object. *In the description of different object types, this optional parameter will be indicated as . AxisN (N = 0, 1, 2) The Nth axis along which the object is cloned, x\_value,y\_value,z\_value\in\mathbb{R} . *Unit = Option::DimensionParam::LengthScale. *Currently, if axes other than the scalar multiple of the x-, y-, z-unit axes are chosen, the result of object array population is undefined. This will be fixed in the next release. Period The spatial increment of the object center along AxisN, value0,value1,value2\in\mathbb{R} . *''valueN'' is the spatial increment along AxisN. *Unit = Option::DimensionParam::LengthScale. NoPeriod The number of periods along AxisN, value0,value1,value2\in\mathbb{I}_{>0} . *''valueN'' is the number of periods along AxisN. Point Builds a point (i.e. populates one cell). (Object Point (Center x_value y_value z_value) (MaterialName/SourceName value) ) Plane Builds a plane, (Object Plane (Center x_value y_value z_value) (MaterialName/SourceName value) (Axis0 x_value y_value z_value) (Axis1 x_value y_value z_value) (Size value0 value1) ) AxisN (N = 0, 1) The two axes that are parallel to any two non-parallel edges of the plane, x\_value,y\_value,z\_value\in\mathbb{R} . *Unit = Option::DimensionParam::LengthScale. *Currently, if axes other than the scalar multiple of the x-, y-, z-unit axes are chosen, the result of the plane population is undefined. This will be fixed in the next release. Size The size along AxisN, value0,value1,value2\in\mathbb{R} . *''valueN'' is the size along AxisN. *Unit = Option::DimensionParam::LengthScale. Block Builds a parallelepiped, (Object Block (Center x_value y_value z_value) (MaterialName/SourceName value) (Axis0 x_value y_value z_value) (Axis1 x_value y_value z_value) (Axis2 x_value y_value z_value) (Size value0 value1 value2) ) AxisN (N = 0, 1, 2) The three axes that are parallel to any three non-parallel edges of the parallelepiped, x\_value,y\_value,z\_value\in\mathbb{R} . *Unit = Option::DimensionParam::LengthScale. *Currently, if axes other than the scalar multiple of the x-, y-, z-unit axes are chosen, the result of the block population is undefined. This will be fixed in the next release. Size The size along AxisN, value0,value1,value2\in\mathbb{R} . *''valueN'' is the size along AxisN. *Unit = Option::DimensionParam::LengthScale. Cylinder Builds a cylinder, (Object Cylinder (Center x_value y_value z_value) (MaterialName/SourceName value) (Axis x_value y_value z_value) (Radius value) (Height value) ) Axis The axis of the cylinder, x\_value,y\_value,z\_value\in\mathbb{R} . *Unit = Option::DimensionParam::LengthScale. Height The size along Axis, value\in\mathbb{R} . *Unit = Option::DimensionParam::LengthScale. Radius The radius of the cylinder, value\in\mathbb{R} . *Unit = Option::DimensionParam::LengthScale.